---
title: "Teacher Portal"
type: entity
created: 2026-04-18
updated: 2026-04-18
sources: ["raw/articles/06-reading-telemetry.md", "raw/articles/05-roster.md", "raw/notes/memory.md"]
tags: [service, teacher-portal, portal, class-management]
---

# Teacher Portal

The Teacher Portal is the primary workspace for `teacher` and `school_admin` roles at [[Pickatale]]. It handles class management, student roster, attention list, learner profiles, and all day-to-day teaching operations.

## Service Details

| Attribute | Value |
|---|---|
| Domain | teacher.readingtester.com |
| Server port | 3116 |
| Client port | 5190 |
| Code location | `/home/ubuntu/teacher-portal/` |
| Database | `teacher_portal` on shared MySQL |
| Status | ✅ Infrastructure built. 1 teacher, 0 real students (2026-04-18) |

## Stack

Next.js + Express backend (legacy stack for this existing project).

## What Teachers Can Do

### Class Management
- Create and archive classes (year level, curriculum territory)
- Add students individually or bulk-import via CSV
- Move students between classes
- Print login cards (student name + username + PIN + QR code + [[Pip]] logo)

### Student Roster
- View all students in each class
- See FK reading level, WCPM, reading progress, miles, vocabulary taps, engagement
- Reset student PIN (shown once in modal)
- Invite parents to link to their child

### Attention List
The attention list is populated by the [[Learner Bot]] nightly run and the [[Intervention Engine]]. It flags students who need attention:

| Flag | Trigger |
|---|---|
| No placement test | First login without placement test |
| 0 books read | No completed reading sessions |
| Low quiz average | Avg quiz score <65% on 2+ consecutive quizzes |
| Inactive | No sessions in 4+ days |

Teachers can dismiss flags, add notes, and mark interventions complete.

### Learner Profiles
Per-student deep view:
- Reading level history and trajectory
- Curriculum objective progress (territory-mapped)
- Vocabulary gap list (words tapped frequently)
- [[Learner Bot]] recommendations and reasoning
- Session history and engagement metrics
- Parent link status

### Assignments (MUST BUILD — not yet live)
- Assign books to a class
- Track completion per student
- Due dates, assignment state

## Dashboard Design

⚠️ **Non-Negotiable (Sig):** Light theme, NOT dark. Dense UI. Class selector on top. Everything visible on one screen.

- All metrics visible: FK levels, WCPM, reading progress, miles, vocabulary taps, engagement
- Big fonts, less clicks, no jargon
- Phase 2 widgets: AI insights ("Sofia is mastering past tense")
- Phase 3 widgets: curriculum objective mastery, cross-nation comparisons

## Student Login Cards

After import, teachers can print login cards:
- **Content:** student name, username, 4-digit PIN (one-time), QR code → `app.readingtester.com?user=username`, school name, [[Pip]] logo, dashed border
- **PIN retention:** 10 minutes only after generation (`pin_reveal_tokens` table). After expiry → teacher must reset PIN.
- **Generated as:** PDF via Puppeteer (using `page.setContent(html)` — never `page.goto(file://)`)

## Known Bug

⚠️ **Known Bug (2026-04-18):** Class name display mismatch — input "Year3Blue" displays as "Year 3 Red" (CLASS ID 4). No transformation code found. Root cause unknown. Must investigate.

## Key Tables Owned

| Table | Status | Purpose |
|---|---|---|
| `teachers` | ✅ | Links teacher user_id to school |
| `classes` | ✅ | Class records (name, year_level, territory) |
| `students` | ✅ | Student accounts (username, pin_hash, learner_id) |
| `memberships` | ✅ | Teacher → school relationships |
| `students_parents` | ✅ | Parent → student links |
| `parent_claims` | MUST BUILD | Pending parent link requests |
| `assignments` | MUST BUILD | Book assignments to classes |
| `teacher_notifications` | MUST BUILD | Alert inbox |

## Related Pages

- [[concepts/user-flows/Teacher Flow]] — full teacher registration and setup flow
- [[concepts/user-flows/Student Flow]] — student account lifecycle
- [[entities/Account Center]] — SSO hub for teacher login
- [[entities/Learner Bot]] — populates attention list and learner profiles